Shareware Extravaganza - Disc 1/ShareWare Extravaganza 1 of 4 (The Ultimate Shareware Company).iso/grprogs/piclab.exe/PICLAB.DOC

Text File | 1989-06-23 | 40KB | 839 lines

PICLAB.DOC

Overview
========

This document describes the PICLAB 1.0 image processing system.  This program
is the first (and only) free public release of this system.  There will be
future commercial version with more features and a better interface at some
later time, but this version will remain the only free one.  Please feel free
to distribute PICLAB any way you like, but include this document with it.

PICLAB is a program for performing mathematical transformations on images
in various formats.  It is intended to work with true-color rather than
color-mapped images.  That is, it deals with images with no restrictions on
the total number of colors in the image.  Each pixel stores complete RGB
values without reference to any external palette.

PICLAB is not designed as a "Paint" program.  Its screen display commands are
primitive (in fact only added as an afterthought), but its hardcopy printing
to HP LaserJet and PaintJet is very powerful (although slow).

This bears repeating: PICLAB IS NOT DESIGNED FOR SCREEN DISPLAYS.  The
limited screen display capabilties provided by its SHOW command are only used
to support its major functions, which are mathmatical enhancement of images
and printing.  Image data is kept completely independent of the devices on
which the images are rendered.  This assures that an image can always be
rendered to the best of its ability on any device, regardless of the
limitations of the devices it has been on in the past.

Because PICLAB currently does not support any devices that can display
images as accurately as PICLAB stores them, you can never really "see" an
image exactly as it is stored.  There are devices this accurate--TrueVision's
Targa 24 board is a popular one--and support for displays like these will
probably be a major part of the enhanced program.  For now, just keep in
mind that what you see on the screen with the "SHOW" command is only a rough
approximation of the real image.

My name and address appears at the end of this document, as well as my
CompuServe ID.  Either is a good way to contact me.


General Operation
=================

After starting PICLAB by typing "PL" at the system command line, the user may
enter any of a number of commands, each of which is performed immediately.
While commands can be taken from a file, PICLAB is not (yet) intended to be a
programming language.  It is an interpreter of the slowest kind, and no
provisions are made for looping constructs or conditional tests.

If an argument is given to the PL command, it is taken as the name of a file
containing PICLAB commands.  This feature can be used to set the PICLAB
variables to settings appropriate for your environment, or for performing
tasks in batch files.  In the latter case, the program specified should have
an EXIT command so that PICLAB will return control to the batch file after the
program is complete.

Commands generally operate on two internal picture buffers called OLD and
NEW.  Most commands start by deleting OLD and renaming NEW to OLD.  They then
perform some transformation on OLD storing the result in NEW.  The command
UNDO swaps NEW and OLD--effectively reversing the last operation.

OLD and NEW are stored on disk.  This decision was made primarily because my
taste in pictures is better than my budget for RAM.  If you are dealing with
simpler pictures, or if you have RAM to burn, you can direct PICLAB to store
OLD and NEW on a RAMdisk.  In MSDOS and similar operating systems, this is
done by typing "SET TMP=D:" at the system command line before running PICLAB,
where D: is the drive or directory specification of the RAMdisk.

PICLAB can read and write images in different file formats.  The LOAD command
is used to read an image in one of these formats into the edit buffers.  The
SAVE is used to write the contents of the edit buffers into one of these
formats.  Every session with PICLAB will generally begin with a LOAD, and end
with a SAVE (or perhaps a PRINT) with some processing in between.  A file may
be loaded from one file format and saved in a different one, thereby
converting among formats.

Command parsing in PICLAB is roughly like that of the system command line.
The line is broken into words that must be separated by spaces; the first
word specifies the actual command and the remaining words are passed to the
command handler as arguments.  The individual command-handling routines are
responsible for interpreting their arguments.  Generally, a word may be
shortened as long as it does not conflict with any other word in the same
context. For example, the LIST COMMANDS command may be abbreviated LIS COM.


Miscellaneous commands
======================

These are all of the commands that do not fit into one of the categories
listed later.  They are, however, the commands that you will use the most--
so I have listed them first.

CALL

    This command calls the external program named by its first argument
    passing along any subsequent arguments to that program.  Many programs do
    not release all of the memory given to them when they terminate, so
    PICLAB will reserve a large portion of memory for itself before calling a
    program.  If you do not have much more memory than PICLAB reserves, this
    may result in the program not being able to run in the memory left.

    If this is a problem, you can use the DOS or SHELL commands (described
    below) to exit to DOS with all of the free memory available.

    The amount of memory reserved by PICLAB in this way can only be changed
    by recompiling the source code with the variable "minalloc" set to a
    different value.  It is not recommended that you do this.  The amount of
    memory reserved is sufficient to save the image in the edit buffer so
    that you can restart PICLAB if necessary without losing it.

CANCEL
UNDO

    These are aliases for the same command, which cancels the most recent
    operation.  If there are point transformations pending that have not yet
    been saved with the TRANSFORM command, these are cancelled and no changes
    are made to the edit buffers.  Otherwise, the NEW and OLD buffers are
    exchanged.

    There are some operations (like SAVE) that do not alter the edit buffers.
    If one of these operations was the last one performed, UNDO will undo
    the operation before that.  There are no arguments to this command.

DOS
SHELL

    These are also aliases for the same command, which in this case calls up
    the DOS command line.  All available memory is released to DOS when this
    command is given, and is reclaimed when DOS is exited.  For this reason,
    some programs that cannot be CALLed may be run from with DOS.

    Any arguments to this command will be passed to the system as a command
    line, and will cause it to return immediately after the command is done.
    One particularly useful action of this program is "DOS COPY /B PDAT PRN",
    which copies the print file to the printer.  "DOS DIR" can be used to view
    file directories when you want to see all files, not just pictures.

EXIT
QUIT

    Aliases for the same command, which exits PICLAB.  If there is a point
    transformation pending, it must be cancelled or saved before exiting.  If
    the exit command is given any arguments, it exits immediately regardless
    of pending transformations.

    Inside a program, exit merely sets a flag so that PICLAB will exit after
    the program is complete.

LIST

    If given without an argument, lists all things that can be listed.  If
    one of these things (e.g. FORMATS, COMMANDS, BUFFERS) is given as an
    argument, the appropriate items are listed.  Especially useful are LIST
    COMMANDS if you forget the name of a command you are looking for and LIST
    BUFFERS to check the size and format of the image in the OLD and NEW edit
    buffers.

PAUSE

    This is primarily for use within programs.  With no arguments, PICLAB
    waits for a key to be pressed before continuing.  If one argument is
    given, PICLAB waits for that number of seconds (but will break early
    if a key is pressed).

PRINT

    This prints the image in the NEW buffer into the file specified by the
    PRINTFILE variable.  The current setting of the PRINTER variable
    determines what codes are sent to the file.  The file (which defaults to
    the name PDAT) can be copied to the printer immediately by issuing the
    DOS COPY /B PDAT PRN command, or can be saved for later printing.

    If the PRINTER variable is set to LASERJET, the DPI variable is used to
    determine which graphics resolution to use.  In any case, each pixel in
    the image will become four dots (2 x 2) on the LaserJet.  For example, a
    320x200 image printed to the LaserJet at 150 DPI will come out to about
    4 1/4 inches wide.

    If PRINTER is set to PAINTJET, color images will be printed at 90 DPI and
    monochrome images at 180 DPI.

    For hard-to-explain reasons, the current release of PICLAB does not allow
    the use of a device name such as PRN in the PRINTFILE variable.  Images
    must therefore be printed to disk and copied to the printer with DOS.

RUN

    This command takes one argument, which is taken as the name of a text file
    containing PICLAB commands.  These are interpreted as if they had been
    typed from the command line, but they are not echoed, and messages are
    turned off while a program runs.  If a second argument to the RUN command
    is the word ECHO, messages are not turned off.

    A program can also be run by giving its name as an argument to the PL
    command when starting PICLAB.

SHOW

    The show command is used to display as much of the image in the NEW
    buffer as will fit on the computer's display screen.  You can select
    what kind of display you want with the "SET DISPLAY" command.

    If arguments are given, the first is used as a horizontal offset into the
    image buffer and the second as a vertical offset.  This can be used to
    look at different parts of an image too big for the screen.

    If no arguments are given, the current values of the XORIGIN and YORIGIN
    variables are used as offsets.

    If any point transformations are pending, the image you see on screen
    reflects the image as it would be AFTER the pending transformation.  This
    can be used to look at the effect of a transformation before saving or
    cancelling it.

    Because PICLAB currently does not support any devices that can display
    images as accurately as PICLAB stores them, you can never really "see"
    an image exactly as it is stored, only an approximation.

SET

    Without any arguments, this command lists all PICLAB variables and their
    current values.  Variables can be numbers, character strings, or TRUE/
    FALSE.  Variables control the specifics of how many commands perform and
    set system defaults.

    If the set command is given one argument, the variable named is cleared.
    That is, set to 0 if it is numeric, to "" if it is a string, and to FALSE
    if it is TRUE/FALSE.

    If SET is given with two arguments, the variable named by the first is
    set to the value specified by the second.  If a numeric variable is
    given a string value, it is set to 0.  String values should not be put in
    quotes.  TRUE/FALSE values may be set by the keywords TRUE/FALSE, YES/NO,
    ON/OFF, or by the numeric values 1/0.

    As of this writing, here are the variables and their uses:

    Variables

    XORIGIN         Used to set the upper left limit of an image for
    YORIGIN         operations such as CLIP and SHOW.  Legal values are
                    0..(size of image - 1).  If image in NEW buffer is stored
                    with bottom-up raster, YORIGIN is measured from the lower
                    left counting upwards.

    PALETTE         Number of colors in palette for saving to limited-
                    color file formats like GIF and PCX.  Legal values are
                    2..256.  If the value is 16, PICLAB assumes you intend
                    the image for an IBM EGA and behaves appropriately.

    CREZ            Color resolution or "depth" for GIF saving.  This value
                    indicates the size of the palette from which an image
                    was digitized.  Legal values are 1..8.

    DPI             Graphics resolution for LaserJet printing.  May be 75,
                    150, or 300.

    MULTIIMAGE      T/F flag for GIF loading.  If true, PICLAB will assume
                    that any GIF files to be loaded may contain multiple
                    images and will act accordingly.  This requires more
                    memory, so it defaults to FALSE.

    MULTIMAP        T/F flag for GIF loading.  If true, PICLAB will assume
                    than any GIF files to be loaded may contain multiple
                    images, and further, that each image may contain a local
                    color map that differs from the global map.  This takes
                    three times the memory of MULTIIMAGE mode, so it should
                    be used only when absolutely necessary.

    PRINTER         String variable indicating what type of printer the PRINT
                    command should address.  For a list of legal values, type
                    LIST PRINTERS.

    PRINTFILE       Disk file to which the PRINT command is directed.  This
                    defaults to "PDAT" but may be changed if you want to go
                    to a different disk, or if you need to print more than
                    one file before exiting.  As of this writing, using the
                    device name "PRN" does not work correctly on some versions
                    of MSDOS, although "/DEV/PRN" usually does.

    TEMPDIR         Name of the drive and directory where PICLAB stores its
                    temporary files (including the NEW and OLD edit buffers).
                    This directory must have six bytes free for every pixel
                    in an image with which you intend to work plus some
                    overhead.  This defaults to the setting of the TMP
                    environment variable.

    PICDIR          Directory in which picture files are stored.  If you use
                    the DIR, LOAD, and SAVE commands without specifying a
                    directory, they will look here.

    FILEFORMAT      Default file format for DIR, LOAD, and SAVE commands.
                    To operate on most file formats it is necessary to set
                    this variable appropriately.  GIF and TGA are special:
                    separate commands (GDIR, TLOAD, etc) exist to load and
                    save these formats regardless of current setting.  For
                    legal values, type LIST FORMATS.

    DISPLAY         Current display adaptor and mode for the SHOW command.
                    For legal values, type LIST DISPLAYS.


Point processes
===============

These are processes that modify each point in an images based only on the
value of that one point.  Most of these commands are performed by modifying a
lookup table that is not applied to the image itself until the TRANSFORM
command is issued.  If one of these commands is issued, a transformation is
said to be 'pending' until it is saved.

HISTOGRAM

    If no arguments are given, this command plots histograms for all planes;
    if one or more arguments are given, a histogram is plotted for each plane
    specified as an argument.  The histograms plotted reflect the image as it
    would be after any pending transformations, so you can look at the
    results of many processes before saving or cancelling them.

    Each vertical bar of the histogram represents the total number of pixels
    in the image with values in the range beginning with the value listed
    below the histogram in hexadecimal.  Each bar covers a range of four
    values and there are 64 bars.  The height of each bar is in logarithmic
    proportion to the frequency of occurrence of values in the range it
    represents.  The bars are automatically scaled so that the tallest one is
    made 20 characters high.

NEGATE

    Arguments are handled as in HISTOGRAM.  This simply inverts each value in
    the lookup table for the planes specified.  This can be used after digi-
    tizing a negative or for special effects.

BRIGHTEN
DARKEN

    These commands add or subtract a constant value from each point in the
    planes specified.  If only one argument is given, all planes are
    brightened by that amount.  Otherwise, arguments are interpreted in
    order, and any arguments that specify planes determine which plane the
    next numerical argument will affect.  For example, BRIGHTEN RED 10 BLUE
    15 would add 10 to the values in the red plane and 15 to those in the
    blue.  The DARKEN command just subtracts the constants rather than adding
    them.  Any values that would be taken out of the 0..255 range by the
    transform are clamped.

    Because this brightening is a linear operation, the image to be
    brightened or darkened should be encoded with a gamma of 1.0.  That is,
    there should be a linear relationship between values in the image and
    intensities on the display.  If this is not the case, gamma correction
    may be applied with the GAMMA command before adjusting brightness.

CONTRAST

    This stretches or squeezes the contrast of an image.  Arguments are
    interpreted like those in BRIGHTEN.  If a given value is positive, the
    image contrast is stretched so that values that were equal to the given
    value become 0, and those that were equal to (255-value) become 255.  If
    the given value is negative, the inverse operation is performed.  Because
    contrast is always stretched equally around the midpoint of the range, it
    is a good idea to brighten or darken an image as necessary to center its
    histogram before performing a contrast stretch.

    Also, the contrast stretching formula operates on color values assuming a
    linear relationship between these values and the intensities they
    represent (as do the BRIGHTEN and DARKEN commands).  Therefore, if an
    image has been scanned with a device with a gamma value not equal to 1.0,
    the image should be gamma corrected before contrast stretching.

GAMMA

    When the voltage applied to the phosphors of a monitor is increased, the
    amount of light emitted by the phosphor increases even more.  The exact
    difference varies from one monitor to the next, but the brightness of the
    phosphors generally increases about 2.8 times as fast.  To compensate for
    this, most video cameras are set to compensate downward.  (Actually,
    cameras compensate for a gamma of 2.2, so that the final image still has
    a non-linearity of about 1.2.  This is done to compensate for the light
    conditions under which TV is normally viewed).

    Images generated by a computer do not generally take this into account.
    Color values are often assumed to be linear, i.e., a point of value 4 is
    twice as bright as a point of value 2, and a point of value 8 is twice as
    bright as a point of value 4.  Images captured from a video camera with
    gamma adjustment should be corrected with a GAMMA 2.2 command before
    applying linear mathematical functions to them (like dithering, or
    brightness and contrast adjustment).  Computer-generated images to be
    displayed on monitors with standard phosphors may be corrected with the
    inverse operation, GAMMA .45 (.45 = 1 / 2.2).  As a convenience, the
    minus sign may be used to indicate inverse transformation, i.e.,
    GAMMA -2.2 does the same thing as GAMMA .45.  I know this will make you
    mathematicians out there cringe, but it is convenient.

    The best way to understand this is to do it.  If you have some images
    that look 'washed out' on output, try contrast stretching first, but
    also try a GAMMA > 1.0.  If an image looks artificially 'intense', try a
    GAMMA < 1.0.

COLOR

    This just copies the gray plane of an image into separate red, green, and
    blue planes.  These planes may then be operated upon separately as if the
    image had been scanned in color.  If first argument is SLICE, then the
    image is pseudo-colored by assigning a different hue to each range of
    intensities in the order blue, cyan, green, yellow, red, magenta, and
    white (light gray).

GRAY

    The inverse of the COLOR command, this takes a color image and maps it to
    shades of gray.  The formula used for conversion to grayscale is the same
    as used by black and white televisions and is designed to mimic the eye's
    response: gray = (.287 * red) + (.589 * green) + (.114 * blue).

TRANSFORM

    This command actually saves the result of a series of point-process
    transformations to the edit buffer.  This must be done before any other
    transformation may be performed on the image.  If you wish to cancel the
    pending transformations without saving them, use UNDO or CANCEL.


Area processes
==============

These processes alter the value of a point based on its value and those of
its immediate neighbors.  The exact neighborhood used depends on the command
but is usually the 3x3 region with the source point in the center.  Unlike
the point processes, these transforms take place immediately.

MEDIAN

    This is used to reduce spot noise from an image.  Each point is replaced
    by the median of the points in its 3x3 area.  That is, the 9 points in
    this area are sorted and the 5th one is taken.  If the one argument to
    this routine is WEIGHTED, then the center point is added twice more to
    the list and the 6th of the 11 points is taken.

    The median filter results in some smoothing, but not as much as with the
    SMOOTH command.  This effect is a little less drastic with the weighted
    median filter.

    This filter will not help reduce periodic or other noise--only small spot
    noise such as from dust on a lens.

SHARPEN

    This applies what is called (somewhat inaccurately) a LaPlace transform
    to the image.  The effect is that edges in the image are sharpened as if
    the image had been re-focused.  Unfortunately, it also increases the
    amount of noise in the image.

    The command can be given a single numerical argument, which specifies the
    severity of the transform.  It is basically a tradeoff between sharpness
    and noise, and defaults to 1.0.  This value provides a noticeable
    increase in both sharpness and noise, and is about the best value for
    sharpening when the purpose is to bring out information.  When applying
    to a real image, a less severe value of .2 to .5 is often better.  Values
    greater than 1.0 should be used only when trying to locate specific
    objects in an image.  They produce too much noise for accurate
    reproduction.

    This function works by amplifying the differences between each point and
    its neighbors.  This has the effect of amplifying high spatial frequency
    details such as edges and noise.

SMOOTH

    This function replaces each point with the average of the values of the 9
    points in its neighborhood.  This has the effect of smoothing the image
    and reducing high frequency effects like aliasing and noise, as well as
    high frequency details.  If an argument is given, it is taken as a value
    of the severity of the transform as with the SHARPEN command.  A value of
    1.0 is exactly as described.  Values less than 1.0 change the center
    value less than if a straight average had been done.  Values greater than
    1.0 are not recommended.  If more smoothing is desired, perform SMOOTH
    more than once rather than with a high value.


Frame processes
===============

These processes operate on all of an image buffer or even both buffers.  Many
of these processes require large amounts of memory and all are performed
immediately.

The first three commands, ADD, SUBTRACT, and AVERAGE, operate on both the OLD
and NEW buffers simultaneously.  To perform these operations on two files
stored on disk, LOAD the first file, then LOAD the second file, which will
move the first one to OLD, then perform the operation.  UNDO after one of
these operations will leave the NEW buffer containing the image FIRST loaded.
You must therefore load the second image again before repeating the command.

ADD
SUBTRACT

    The ADD command adds the OLD and NEW edit buffers storing the result in
    the NEW buffer.  If the only argument to the command is WRAP, then values
    that are taken out of the 0..255 range by the addition are taken mod
    255; otherwise, values are clamped.  SUBTRACT, as you would expect,
    subtracts the NEW buffer from the OLD, storing the result in NEW.  No
    arguments.

AVERAGE

    This command averages the OLD and NEW buffers, storing the result in NEW.
    This can be used to reduce random digitizer noise by averaging the results
    of different samplings.  Can also be used to produce a double-exposure
    effect when two different images are averaged.  No arguments.

CLIP

    If no arguments are given, image is clipped from (XORIGIN,YORIGIN) to
    lower right corner (upper right for bottom-up images).  If two arguments
    are given, the image is clipped from (XORIGIN,YORIGIN) to the horizontal
    and vertical size specified by the arguments.  XORIGIN and YORIGIN are set
    to 0 after this operation.  One argument is an error--more than two are
    ignored.

EXPAND

    This command increases the size of the image to the width and height
    specified by its two arguments by adding extra rows and columns of
    pixels.  If a third argument is given, it can be either BLACK or WHITE
    to indicate what color the extra pixels should be.  Multiple images can
    be placed in a montage by using EXPAND and OVERLAY.  Parts of an image
    may be joined with these functions as well, but it is not recommended
    for separately digitized image pieces, as no mosaicking (spelled right,
    honest) is performed.

MIRROR

    Flips the image horizontally.  No Arguments.

OVERLAY

    Overlays the image in the NEW buffer on top of the OLD buffer.  The
    image in the NEW buffer must not be larger than the image it is to
    overlay.  If two arguments are given, they are used as the horizontal
    and vertical offsets into the base image at which the overlay image
    is to be placed.  Otherwise, XORIGIN and YORIGIN are used.

RESCALE

    This resamples the image at a different resolution.  This is useful for
    scaling images up to a larger size for printing, or for scaling them down
    for display.  It is recommended that image data always be saved at its
    original sampling resolution to preserve as much data as possible and
    only scaled when necessary to conform to hardware.

    If only one argument is given, horizontal and vertical resolution are
    both increased in the given proportion.  For example, if a 320 x 240
    image is in the NEW buffer when the command RESCALE 1.5 is given, the NEW
    buffer will contain the same image at 480 x 360.

    More useful, though, is the case where two arguments are present.  In
    this case, the arguments are treated directly as the new horizontal and
    vertical resolution of the image.  The transformation above could be
    expressed as RESCALE 360 480.  This is most often used to compensate for
    differing aspect ratios.  For example, a 320 x 400 from an Amiga can be
    rescaled to 320 x 200 to be viewed on a VGA, or to 720 x 540 for printing
    on the HP PaintJet.

REVERSE

    Images are stored in either top-down or bottom-up directions.  Most of
    the image processing techniques do not care which, so it is usually the
    file format used to import the image that determines how it is stored.

    This command changes the storage order of an image from top-down to
    bottom-up or vice versa.  This is used primarily to save an image loaded
    from a file in one format (like PCX) to a format requiring the opposite
    order (like GIF).

    TGA files can be stored either way, and contain information in the header
    specifying which way they are stored.  Thus, any image can be saved in
    TGA format at any time with minimal memory usage.

ROTATE

    This is used to rotate an image in 90-degree increments.  The single
    argument may specify 1, 2, or 3, in which case that number of clockwise
    90-degree rotations are performed.  If a number >= 90 is given as the
    argument, the image is rotated that number of degrees (truncated to the
    nearest 90-degree increment).

    This is very useful for rotating screen-oriented images for printing on
    paper.  Because this operation requires large amounts of memory for large
    images, it is recommended in this case to rotate the image before scaling
    it up to size for printing.


File I/O commands
=================

DIR

    List all files in the PICDIR directory in the current file format.  If an
    argument is given, files in that directory are listed.  No other file
    specifications can be given.

GDIR
TDIR

    As with DIR, files from PICDIR or from the directory given as the sole
    argument are listed.  The GDIR command always lists GIF format files
    while the TDIR command always lists Targa format files regardless of the
    current setting of FILEFORMAT.

LOAD

    Loads a file in the current file format into the NEW buffer, moving the
    current contents of the NEW buffer to OLD.  Any arguments are passed
    along to the function that handles loading for the current format and
    are interpreted by that routine.  The first argument is always the file
    to be loaded, but other arguments vary with the format.  Below is a list
    of arguments interpreted by the various file formats:

    TARGA       No arguments are interpreted.  Targa files are completely
                self descriptive and need no extra directions for loading.

    GIF         No arguments are interpreted from the command line, but
                GIF loading is affected by the values of the variables
                MULTIIMAGE and MULTIMAP.  These are both set false by
                default to save memory, but one or both may be necessary to
                load some files.  LOAD will issue warnings when loading a
                multiimage or multimap file with improper settings.

    RIX         Only uncompressed 256-color file formats from ColoRix are
                supported--the old EGAPaint files are not.  Because so many
                different file extensions are used, file extension must be
                specified when loading.  The global palette is taken from the
                image file regardless of the file extension, unlike ColoRix.

    IP          This is the Amiga DigiView's raw storage format.  It consists
                of nothing but three planes of data, one byte per pixel,
                followed by 12 bytes not associated with the image.  Because
                there is no size information in a IP file, the width and
                height of the image must be specified as the second and third
                arguments to LOAD.  A fourth argument may be the words COLOR
                or MONO to specify the number of planes.  COLOR is default.

    RAW         Raw files are even simpler than IP.  One file per plane,
                one byte per pixel, nothing else.  Arguments must be the same
                as those for IP format.  The file for plane one must have a
                .R8 extension, and the second and third planes, if any, must
                have .G8 and .B8.

GLOAD
TLOAD

    Load image in GIF (GLOAD) or Targa (TLOAD) format regardless of the
    current setting of FILEFORMAT.  No arguments to either function.

SAVE

    Saves the image in the NEW buffer to the file specified by the first
    argument.  Subsequent arguments are passed along to the file save routine
    of the current file format, and are interpreted as follows:

    TARGA       If one of the arguments is the number 16, 24, or 32, it is
                used as the number of bits per pixel stored in the file.

    GIF         If the word INTERLACE is given as an argument, the file is
                stored in GIF interlaced format.  A GIF file is always saved
                as a single-image file with the screen size and image size
                identical.  Because color GIF files are limited to a palette
                of 256 colors, color images will be dithered on output to a
                GIF file, and will therefore lose information.  Monochrome
                images are stored at full 256-shade resolution.

                It can take several minutes to determine the best color
                palette, so be patient.

    RIX         Saving of images in these formats is not supported.  They may
    IP          only be loaded and saved in Targa or GIF format.
    RAW

GSAVE
TSAVE

    These save the NEW buffer to the file named by the first argument in GIF
    (GSAVE) or Targa (TSAVE) format regardless of the current setting of
    FILEFORMAT.  See above for appropriate arguments.


Warnings and Errors
===================

"Command arguments ignored"

    This warning occurs when you give a command more arguments than it needs.
    Review the syntax of the command for an explanation.

"Open files were closed"

    This indicates that a command halted for some reason while files were open.
    PICLAB has closed the files but data may be lost.

"Probable information loss"

    This warning is very common and should be taken lightly.  It indicates that
    some transformation has been performed that is not reversible.  Most of
    the time, the initial image will be safely stored in a disk file, or
    recoverable with UNDO, so this is unimportant.

"Assertion failure; contact author"

    The is printed only in places I think are unreachable.  This message
    indicates a serious error, and action (such as saving the working file
    and exiting the program) should be taken immediately.

"Insufficient memory"

    There is not enough memory to perform the command issued with the current
    environment.  This is most common in frame processes like ROTATE,
    and with GIF loading with MULTIIMAGE and MULTIMAP set ON.  In the
    latter case, those variables can be set to OFF before loading.  In the
    former, there is not much alternative but to clip the image to a smaller
    size or try to provide more memory.

"Miscellaneous file I/O"

    File open or write failed.  Could be bad or full disk.  Retrying may help.

"Unexpected end of file"

    File read failed.  This may occur when loading a file that is not encoded
    in the correct format, or when loading a RAW or IP file when the size is
    specified incorrectly.  CLIP may sometimes be used to recover.

"LZW compression/decompression"

    Usually the result of a bad GIF file.

"Unrecognized file format or bad file"

    The LOAD command encountered something in the file not consistent with the
    file format being loaded.  Usually this is because you specified the wrong
    format, but may also occur on a bad or incorrectly encoded file.

"Image buffer empty"

    You attempted a transformation when no image is in the edit buffers.

"Point transform pending; issue TRANSFORM command"

    The command you issued cannot be performed until any pending point trans-
    formations are either saved with the TRANSFORM command or cancelled with
    the UNDO command.

"Illegal parameter values"

    This is a catch-all command syntax error.  Review the syntax of the command
    you are issuing.

"File not found"

    File open in LOAD command failed.  Check that the file is in the proper
    directory by issuing a DIR command.  Also check for correct spelling.


Technical Stuff
===============

The buffers NEW and OLD are stored in the disk files PLTEMP1.* and PLTEMP2.*
on the drive and directory specified by the TEMPDIR variable.  Which file is
which is basically random--they are switched by most commands, but not by
all.  They are in raw 8 bits per pixel, one file per plane.  For color
images, that means there are 3 files with file extensions of R8, G8, and B8.
For monochrome images there is only an R8 file.

All image processing operations are performed to 8-bit unsigned precision.
File formats that have limited palettes like GIF may be loaded without loss of
information, but saving an image to these file formats will require that
PICLAB dither, even if no changes were made between loading and saving.


Acknowledgements
================

Many people have helped me bring this project together--some with helpful
hints or advice, others with direct help, and others by the no less helpful
device of inspiration.  While I cannot remember all of them, a few deserve
mention (in no particular order):

Dale Brunken, my employer, who looked the other way when the insurance
company's laser printers generated something besides actuarial tables.

Hewlett Packard technical support staff, who provided all the information I
needed to generate good results on their printers.

John Bridges, whose IMGTOOLS package served both as inspiration and as a
yardstick to measure the performance of my routines.  He still has me beaten,
but I am working.  If the performance of PICLAB is a problem for you, his
package is certainly a good investment.  His conversion of Targa files to
GIF format is also superior to mine.

Bob Currier, who sent me a tape full of sample images to play with.  They
were very useful in tuning the image processing code.

Jim Maxey, who probably uses PICLAB more than anyone else, for nagging me
into fixing problems and sending me some of his wonderful pictures.

Phil Shatz, another PICLAB user, for suggestions and publicity.

And finally, and perhaps most importantly, the many other developers on the
PICS forum of CompuServe.


Legal Stuff
===========

Below are listed the owners of various trademarks that are either mentioned
in this document or are likely to be mentioned in it in the future:

'DigiView' is a trademark of NewTek Incorporated.

'GIF' and 'Graphics Interchange Format' are trademarks of CompuServe
Incorporated, an H&R Block company.

'PaintJet' and 'LaserJet' are trademarks of Hewlett Packard Corporation.


Author
======

Lee Daniel Crocker
1380 Jewett Ave
Pittsburg, CA  94565

Best way to reach me: Type GO PICS on CompuServe and leave mail to user ID
[73407,2030].  I read these messages two or three times a week.

I am also reachable on BIX as "lcrocker", but I do not visit there as often.

June 23, 1989